native-hdr-histogram

native-hdr-histogram

node.js bindings for hdr histogram C implementation(version 0.9.10).

HDR Histogram is designed for recoding histograms of value measurements in latency and performance sensitive applications. Measurements show value recording times as low as 3-6 nanoseconds on modern (circa 2014) Intel CPUs. A Histogram's memory footprint is constant, with no allocation operations involved in recording data values or in iterating through them.

• from hdr histogram website

This library is blazingly fast, and you can use it to record histograms with no overhead. Linux, Mac OS X and Windows are all supported.

• Installation
• Example
• API
• Licence & copyright

Install

npm i native-hdr-histogram --save

If you see any errors, you might need to configure your system to compile native addons: follow the instructions at node-gyp.

Example

'use strict'

const Histogram = require('native-hdr-histogram')
const max = 1000000
const key = 'record*' + max
const histogram = new Histogram(1, 100)

console.time(key)
for (let i = 0; i < max; i++) {
  histogram.record(Math.floor((Math.random() * 42 + 1)))
}
console.timeEnd(key)

console.log('80 percentile is', histogram.percentile(80))
console.log('99 percentile is', histogram.percentile(99))

console.log(histogram.percentiles())

API

• Histogram
• histogram#record()
• histogram#min()
• histogram#max()
• histogram#mean()
• histogram#stddev()
• histogram#percentile()
• histogram#percentiles()
• histogram#encode()
• histogram#decode()
• histogram#reset()

---

Histogram(lowest, max, figures)

Create a new histogram with:

• lowest: is the lowest possible number that can be recorded (default 1).
• max: is the maximum number that can be recorded (default 100).
• figures: the number of figures in a decimal number that will be maintained, must be between 1 and 5 (inclusive) (default 3).

---

histogram.record(value)

Record value in the histogram. Returns true if the recording was successful, false otherwise.

---

histogram.min()

Return the minimum value recorded in the histogram.

---

histogram.max()

Return the maximum value recorded in the histogram.

---

histogram.mean()

Return the mean of the histogram.

---

histogram.stddev()

Return the standard deviation of the histogram.

---

histogram.percentile(percentile)

Returns the value at the given percentile. percentile must be > 0 and <= 100, otherwise it will throw.

---

histogram.percentiles()

Returns all the percentiles.

Sample output:

[ { percentile: 0, value: 1 },
  { percentile: 50, value: 22 },
  { percentile: 75, value: 32 },
  { percentile: 87.5, value: 37 },
  { percentile: 93.75, value: 40 },
  { percentile: 96.875, value: 41 },
  { percentile: 98.4375, value: 42 },
  { percentile: 100, value: 42 } ]

---

histogram.encode()

Returns a Buffer containing a serialized version of the histogram

---

histogram.decode(buf)

Reads a Buffer and deserialize an histogram.

---

histogram.reset()

Resets the histogram so it can be reused.

Acknowledgements

This project was kindly sponsored by nearForm.

The pre-compilation work of this project is only possible because of mapbox's amazing work on node-pre-gyp. A lot of the functionality enabled is following the example set by their node-sqlite3 library.

License

This library is licensed as MIT

HdrHistogram_c is licensed as BSD license

zlib is licensed as zlib License

The scripts used in the scripts folder are modified BSD licensed scripts from the node-sqlite3 libary.